NEW!
Download Winamp3! - Talk Back In The
Forums!

NSDN Home

Beta
News

Winamp 2x Info

Winamp 3x Info

Code Vault

Glossary

N A V I G A T E

NSDN Home

Winamp
2x
User
Docs
Walkthrough
FAQ

Dev
Docs
Making
Skins
Base
Skin
Main
Window
Equalizer
Playlist
Minibrowser
WVS
Window
Cursors
Config
files
WSZ
Submit
Skins
FAQ

Winamp
SDK
Winamp
API
FAQ

Writing
Plug-ins
In
SDK
Out
SDK
General
SDK
DSP
SDK
Vis
SDK
Lang
Packs
Submit
Plug-ins
FAQ

Winamp 3x
NSIS
WVS
Code Vault
Glossary

Frontend.h for Winamp API

Frontend.h contains lots of
information on how to control Winamp through the Win32
Message API. Just compile it into your plugins to have
access to to our #defines.

CLICK
HERE TO DOWNLOAD
FRONTEND.H

Winamp
Application Programming Interface

How to communicate with Winamp from
plug-ins and other applications.

Using the Command Line
Interface

Using Windows
Messages

Determining the Winamp
window

Using WM_COMMAND
messages

Using WM_USER
messages

Using WM_COPYDATA
messages

Examples

Other Useful
techniques

Conclusion

Using the command line interface to control
Winamp

The simplest, easiest, least powerful
way of controlling Winamp is to execute winamp.exe
yourself. By simply calling winamp.exe with various
command line options, you do a number of things. For
example:

C:\path\to\winamp\winamp.exe /ADD
C:\mp3\whatever.mp3
(Adds
C:\mp3\whatever.mp3 to the playlist of a running
Winamp, if Winamp is running, otherwise it opens
Winamp and plays it
outright)

C:\path\to\winamp\winamp.exe
/NEW
(Creates a new
instance of Winamp, even if Winamp is already
running)

C:\path\to\winamp\winamp.exe
C:\mp3\file.mp3
(Plays the
file C:\mp3\file.mp3, regardless of whether or not
Winamp is
open)

C:\path\to\winamp\winamp.exe
/CLASS="myclassname"
(Opens
Winamp with a different Window Class name
"myclassname")
As you might notice,
what you can actually do using the command line
interface is pretty limited. It is really easy to get
started with, though. You can also specify multiple
files and or directories on the command line, such as:

C:\path\to\winamp\winamp.exe /NEW "C:\my
mp3s\" "C:\bigplaylist.pls" "C:\download\new song.mp3"

Using Windows Messages to control
Winamp

Determining the Winamp
window

Winamp is a 32-bit Windows
application. Having said that, we'll assume some basic
knowledge of 32 bit Windows programming. Winamp can be
controlled using the Windows Message system. Before you
can send Winamp messages, you have to determine its
Window Handle. There are two primary ways of doing that,
one for external applications, and another for
plug-ins.

Plug-ins simply get passed a HWND to
Winamp in their respective structures. The variable is
usually named hwndWinamp or hwndParent.

External
applications can find the Winamp window using the
following pieces of code:

C/C++:

HWND hwndWinamp =
FindWindow("Winamp v1.x",NULL);

VBasic:

Public Declare
Function FindWindow Lib "user32" Alias "FindWindowA"
(ByVal lpClassName As String, ByVal lpWindowName As
String) As Long
Dim hwndWinamp as
long
hwndWinamp = FindWindow("Winamp
v1.x",vbNullString)

Delphi Pascal:

var hwndWinamp :
THandle;
hwndWinamp := FindWindow('Winamp v1.x',
nil);
Note that this code uses the
FindWindow() function to find a window of any title
whose class name is "Winamp v1.x". All versions of
Winamp 1.x and 2.x have the class "Winamp v1.x", unless
changed using the /CLASS= switch (see above). Note that
if you want to run multiple Winamp's and easily tell the
difference between them, you can use the /CLASS=
switch.

Message types Winamp
understands

Winamp responds to three
messages in particular: WM_USER, WM_COMMAND, and
WM_COPYDATA. WM_USER and WM_COPYDATA allow you to
control some of the more advanced aspects of Winamp
while WM_COMMAND lets you do simple things such as
simulate the pause button being
pressed.

WM_COMMAND Messages

Previous track
button

40044

Next track
button

40048

Play
button

40045

Pause/Unpause
button

40046

Stop
button

40047

Fadeout and
stop

40147

Stop after
current track

40157

Fast-forward 5
seconds

40148

Fast-rewind 5
seconds

40144

Start of
playlist

40154

Go to end of
playlist

40158

Open file
dialog

40029

Open URL
dialog

40155

Open file info
box

40188

Set time
display mode to elapsed

40037

Set time
display mode to remaining

40038

Toggle
preferences screen

40012

Open
visualization options

40190

Open
visualization plug-in options

40191

Execute current
visualization plug-in

40192

Toggle about
box

40041

Toggle title
Autoscrolling

40189

Toggle always
on top

40019

Toggle
Windowshade

40064

Toggle Playlist
Windowshade

40266

Toggle
doublesize mode

40165

Toggle
EQ

40036

Toggle playlist
editor

40040

Toggle main
window visible

40258

Toggle
minibrowser

40298

Toggle
easymove

40186

Raise volume by
1%

40058

Lower volume by
1%

40059

Toggle
repeat

40022

Toggle
shuffle

40023

Open jump to
time dialog

40193

Open jump to
file dialog

40194

Open skin
selector

40219

Configure
current visualization plug-in

40221

Reload the
current skin

40291

Close
Winamp

40001

Moves back 10
tracks in playlist

40197

Show the edit
bookmarks

40320

Adds current
track as a bookmark

40321

Play audio
CD

40323

Load a preset
from EQ

40253

Save a preset
to EQF

40254

Opens load
presets dialog

40172

Opens auto-load
presets dialog

40173

Load default
preset

40174

Opens save
preset dialog

40175

Opens auto-load
save preset

40176

Opens delete
preset dialog

40178

Opens delete an
auto load preset dialog

40180

WM_USER
Messages

WM_USER messages are sent using
SendMessage(). In C/C++, you can send these messages by
calling:

int
ret=SendMessage(hwndWinamp,WM_USER, data, id);

data is used by many of the messages, but
not all. For messages where the meaning of data is not
defined, simply use 0.

Here is a list of the
currently supported ids that you can use from within
Winamp plug-ins or from other applications (see plug-in
only WM_USER messages, below, for more):

0

Retrieves the version
of Winamp running. Version will be 0x20yx for
2.yx. This is a good way to determine if you did
in fact find the right window, etc.

100

Starts playback. A lot
like hitting 'play' in Winamp, but not exactly the
same

101

Clears Winamp's
internal playlist.

102

Begins play of
selected track.

103

Makes Winamp change to
the directory C:\\download

104

Returns the status of
playback. If 'ret' is 1, Winamp is playing. If
'ret' is 3, Winamp is paused. Otherwise, playback
is stopped.

105

If data is 0, returns
the position in milliseconds of playback. If data
is 1, returns current track length in seconds.
Returns -1 if not playing or if an error
occurs.

106

Seeks within the
current track. The offset is specified in 'data',
in milliseconds.

120

Writes out the current
playlist to Winampdir\winamp.m3u, and returns the
current position in the playlist.

121

Sets the playlist
position to the position specified in tracks in
'data'.

122

Sets the volume to
'data', which can be between 0 (silent) and 255
(maximum).

123

Sets the panning to
'data', which can be between 0 (all left) and 255
(all right).

124

Returns length of the
current playlist, in tracks.

125

Returns the position
in the current playlist, in tracks (requires
Winamp 2.05+).

126

Retrieves info about
the current playing track. Returns samplerate
(i.e. 44100) if 'data' is set to 0, bitrate if
'data' is set to 1, and number of channels if
'data' is set to 2. (requires Winamp
2.05+)

127

Retrieves one element
of equalizer data, based on what 'data' is set
to.

0-9

The 10
bands of EQ data. Will return 0-63 (+20db -
-20db)

10

The
preamp value. Will return 0-63 (+20db -
-20db)

11

Enabled. Will return zero if disabled,
nonzero if
enabled.

128

Autoload. Will return
zero if disabled, nonzero if enabled. To set an
element of equalizer data, simply query which item
you wish to set using the message above (127),
then call this message with data

129

Adds the specified
file to the Winamp bookmark list

135

Restarts
Winamp

Here is a
list of the currently supported ids that you can only
use from within Winamp plug-ins (since they depend on
running in the same process as Winamp):

200

Sets the current skin.
'data' points to a string that describes what skin
to load, which can either be a directory or a .zip
file. If no directory name is specified, the
default Winamp skin directory is
assumed.

201

Retrieves the current
skin directory and/or name. 'ret' is a pointer to
the Skin name (or NULL if error), and if 'data' is
non-NULL, it must point to a string 260 bytes
long, which will receive the pathname to where the
skin bitmaps are stored (which can be either a
skin directory, or a temporary directory when
zipped skins are used) (Requires Winamp
2.04+).

202

Selects and executes a
visualization plug-in. 'data' points to a string
which defines which plug-in to execute. The string
can be in the following formats:

vis_whatever.dll

Executes the default module in
vis_whatever.dll in your plug-ins
directory.

vis_whatever.dll,1

executes the second module in
vis_whatever.dll

C:\path\vis_whatever.dll,1

executes the second module in
vis_whatever.dll in another
directory

211

Retrieves (and returns
a pointer in 'ret') a string that contains the
filename of a playlist entry (indexed by 'data').
Returns NULL if error, or if 'data' is out of
range.

212

Retrieves (and returns
a pointer in 'ret') a string that contains the
title of a playlist entry (indexed by 'data').
Returns NULL if error, or if 'data' is out of
range.

241

Opens an new URL in
the minibrowser. If the URL is NULL it will open
the Minibrowser window

242

Returns 1 if the
internet connecton is available for
Winamp

243

Asks Winamp to update
the information about the current
title

245

Sets the current
playlist item

246

Retrives the current
Minibrowser URL into the buffer.

247

Flushes the playlist
cache buffer

248

Blocks the Minibrowser
from updates if value is set to 1

249

Opens an new URL in
the minibrowser (like 241) except that it
will work even if 248 is set to 1

250

Returns the status of
the shuffle option (1 if set)

251

Returns the status of
the repeat option (1 if set)

252

Sets the status of the
suffle option (1 to turn it on)

253

Sets the status of the
repeat option (1 to turn it
on)

WM_COPYDATA
Messages

WM_COPYDATA messages are sent using
SendMessage() and a COPYDATASTRUCT structure. In C/C++,
you can send these messages by using:

COPYDATASTRUCT
cds;
cds.dwData = id;
cds.lpData =
(void*)data;
cds.cbData =
data_length;
SendMessage(hwndWinamp,WM_COPYDATA,(WPARAM)NULL,(LPARAM)&cds);

To
get the directory where skin bitmaps are stored (useful
for plug-ins to support their own skins):

char
skin_dir[260];
SendMessage(hwndWinamp,WM_USER,(LPARAM)skin_dir,201);

Other Useful Techniques

There
are a number of other things you can do to query/control
Winamp. For example, this C/C++ code fragment will get
the title of the current song playing in Winamp. A
simple explanation is that it retrieves Winamp's window
title, removes the trailing ' - Winamp'.

char
this_title[2048],*p;
GetWindowText(hwndWinamp,this_title,sizeof(this_title));
p
= this_title+strlen(this_title)-8;
while (p >=
this_title)
{

if
(!strnicmp(p,"- Winamp",8))
break;
p--;

}
if (p >=
this_title) p--;
while (p >= this_title
&& *p == ' ')
p--;
*++p=0;

Conclusion

You
can control Winamp. It doesn't just own you, you own it.
If this is still unclear to you, look through the
various plug-in SDKs/examples. They'll show these
facilities in action. If you'd like to offer any advice
for these pages, e-mail it to [email-masked].

Click here
to
make us your
homepage

Click here for
help or feedback

Promote
Winamp!

Click
Here

Copyright Nullsoft Inc. 2002 - [ Disclaimer | Terms of Service | Labelled with ICRA |
Advertise
with us! ]